@verajs/renderer 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +729 -226
  2. package/dist/development/vera-renderer-elements.d.ts +39 -0
  3. package/dist/development/vera-renderer-elements.d.ts.map +1 -0
  4. package/dist/development/vera-renderer-elements.js +193 -0
  5. package/dist/development/vera-renderer-elements.js.map +1 -0
  6. package/dist/development/vera-renderer-hydrate-slots.d.ts +94 -0
  7. package/dist/development/vera-renderer-hydrate-slots.d.ts.map +1 -0
  8. package/dist/development/vera-renderer-hydrate-slots.js +325 -0
  9. package/dist/development/vera-renderer-hydrate-slots.js.map +1 -0
  10. package/dist/development/vera-renderer-hydration.d.ts +332 -0
  11. package/dist/development/vera-renderer-hydration.d.ts.map +1 -0
  12. package/dist/development/vera-renderer-hydration.js +864 -0
  13. package/dist/development/vera-renderer-hydration.js.map +1 -0
  14. package/dist/development/vera-renderer-keyed.d.ts +25 -8
  15. package/dist/development/vera-renderer-keyed.d.ts.map +1 -1
  16. package/dist/development/vera-renderer-keyed.js +843 -268
  17. package/dist/development/vera-renderer-keyed.js.map +1 -1
  18. package/dist/development/vera-renderer-multi-window.d.ts +5 -0
  19. package/dist/development/vera-renderer-multi-window.d.ts.map +1 -0
  20. package/dist/development/vera-renderer-multi-window.js +40 -0
  21. package/dist/development/vera-renderer-multi-window.js.map +1 -0
  22. package/dist/development/vera-renderer-namespaces.d.ts +64 -0
  23. package/dist/development/vera-renderer-namespaces.d.ts.map +1 -0
  24. package/dist/development/vera-renderer-namespaces.js +94 -0
  25. package/dist/development/vera-renderer-namespaces.js.map +1 -0
  26. package/dist/development/vera-renderer-native-elements.d.ts +13 -0
  27. package/dist/development/vera-renderer-native-elements.d.ts.map +1 -0
  28. package/dist/development/vera-renderer-native-elements.js +231 -0
  29. package/dist/development/vera-renderer-native-elements.js.map +1 -0
  30. package/dist/development/vera-renderer-portal.d.ts +29 -0
  31. package/dist/development/vera-renderer-portal.d.ts.map +1 -0
  32. package/dist/development/vera-renderer-portal.js +167 -0
  33. package/dist/development/vera-renderer-portal.js.map +1 -0
  34. package/dist/development/vera-renderer-profiler.d.ts +113 -138
  35. package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
  36. package/dist/development/vera-renderer-profiler.js +2428 -2101
  37. package/dist/development/vera-renderer-profiler.js.map +1 -1
  38. package/dist/development/vera-renderer-slots.d.ts +88 -92
  39. package/dist/development/vera-renderer-slots.d.ts.map +1 -1
  40. package/dist/development/vera-renderer-slots.js +1834 -1237
  41. package/dist/development/vera-renderer-slots.js.map +1 -1
  42. package/dist/development/vera-renderer-spread.d.ts +8 -29
  43. package/dist/development/vera-renderer-spread.d.ts.map +1 -1
  44. package/dist/development/vera-renderer-spread.js +542 -461
  45. package/dist/development/vera-renderer-spread.js.map +1 -1
  46. package/dist/development/vera-renderer-tag.d.ts +12 -3
  47. package/dist/development/vera-renderer-tag.d.ts.map +1 -1
  48. package/dist/development/vera-renderer-tag.js +671 -494
  49. package/dist/development/vera-renderer-tag.js.map +1 -1
  50. package/dist/development/vera-renderer-until.d.ts +24 -0
  51. package/dist/development/vera-renderer-until.d.ts.map +1 -0
  52. package/dist/development/vera-renderer-until.js +83 -0
  53. package/dist/development/vera-renderer-until.js.map +1 -0
  54. package/dist/development/vera-renderer.d.ts +77 -96
  55. package/dist/development/vera-renderer.d.ts.map +1 -1
  56. package/dist/development/vera-renderer.js +2401 -2061
  57. package/dist/development/vera-renderer.js.map +1 -1
  58. package/dist/vera-renderer-elements.min.js +2 -0
  59. package/dist/vera-renderer-elements.min.js.map +1 -0
  60. package/dist/vera-renderer-hydrate-slots.min.js +2 -0
  61. package/dist/vera-renderer-hydrate-slots.min.js.map +1 -0
  62. package/dist/vera-renderer-hydration.min.js +3 -0
  63. package/dist/vera-renderer-hydration.min.js.map +1 -0
  64. package/dist/vera-renderer-keyed.min.js +1 -1
  65. package/dist/vera-renderer-keyed.min.js.map +1 -1
  66. package/dist/vera-renderer-multi-window.min.js +2 -0
  67. package/dist/vera-renderer-multi-window.min.js.map +1 -0
  68. package/dist/vera-renderer-namespaces.min.js +2 -0
  69. package/dist/vera-renderer-namespaces.min.js.map +1 -0
  70. package/dist/vera-renderer-native-elements.min.js +2 -0
  71. package/dist/vera-renderer-native-elements.min.js.map +1 -0
  72. package/dist/vera-renderer-portal.min.js +2 -0
  73. package/dist/vera-renderer-portal.min.js.map +1 -0
  74. package/dist/vera-renderer-slots.min.js +1 -1
  75. package/dist/vera-renderer-slots.min.js.map +1 -1
  76. package/dist/vera-renderer-spread.min.js +1 -1
  77. package/dist/vera-renderer-spread.min.js.map +1 -1
  78. package/dist/vera-renderer-tag.min.js +1 -1
  79. package/dist/vera-renderer-tag.min.js.map +1 -1
  80. package/dist/vera-renderer-until.min.js +2 -0
  81. package/dist/vera-renderer-until.min.js.map +1 -0
  82. package/dist/vera-renderer.min.js +1 -1
  83. package/dist/vera-renderer.min.js.map +1 -1
  84. package/package.json +52 -9
  85. package/dist/development/vera-renderer-hydrate.d.ts +0 -118
  86. package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
  87. package/dist/development/vera-renderer-hydrate.js +0 -3092
  88. package/dist/development/vera-renderer-hydrate.js.map +0 -1
  89. package/dist/vera-renderer-hydrate.min.js +0 -2
  90. package/dist/vera-renderer-hydrate.min.js.map +0 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @verajs/renderer
2
2
 
3
- The DOM renderer for VeraJS — <!--size:renderer.gzip-->4.58 KB<!--/size:renderer.gzip--> gzipped,
3
+ The DOM renderer for VeraJS — <!--size:renderer.gzip-->5.69 KB<!--/size:renderer.gzip--> gzipped,
4
4
  no dependencies, no build step required.
5
5
 
6
6
  Tagged templates parse once and clone; every render after the first walks only the value slots, so
@@ -18,7 +18,7 @@ there is no second call to make.
18
18
 
19
19
  <!-- recipe -->
20
20
  ```js
21
- import { init, createStore, render, wire, html } from '@verajs/core';
21
+ import { init, createStore, wire, html } from '@verajs/core';
22
22
  import { renderer } from '@verajs/renderer';
23
23
 
24
24
  wire([renderer]);
@@ -27,9 +27,10 @@ customElements.define(
27
27
  'click-counter',
28
28
  class extends HTMLElement {
29
29
  connectedCallback() {
30
- init(this, { mode: 'open' });
31
- const state = createStore({ count: 0 });
32
- render(() => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`);
30
+ init({ host: this, shadow: 'open' }, () => {
31
+ const state = createStore({ count: 0 });
32
+ return () => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`;
33
+ });
33
34
  }
34
35
  }
35
36
  );
@@ -37,13 +38,21 @@ customElements.define(
37
38
  document.body.append(document.createElement('click-counter'));
38
39
  ```
39
40
 
40
- Without it, core has no renderer at all: `render()` warns once in development and puts
41
+ Without it, core has no renderer at all: a component warns once (in every build) and puts
41
42
  nothing on the page. `@event`, `.prop` and `?bool` bindings are the first things to go missing.
42
43
 
44
+ **One renderer serves one core.** A renderer connects to the core whose `wire` it was last handed. On
45
+ a CDN page with two apps that load DIFFERENT copies of core (two versions) but the SAME renderer
46
+ URL, the second app's `wire([renderer])` takes the renderer over, and the first app's renders lose
47
+ their tracking. The renderer says so when it happens — `[vera] renderer-two-cores` (the code's entry
48
+ at `verajs.dev/e/renderer-two-cores` explains it). Give each app its own renderer URL beside its own core,
49
+ or share one core between them. (Under a bundler, or two apps on the same core URL, there is one
50
+ core and nothing to do.)
51
+
43
52
  ### `renderInto(result, container)`
44
53
 
45
54
  The same write, called directly — no reactivity, no lifecycle, no custom element. `wire([renderer])`
46
- registers exactly this function, so a component's `render()` ends up here; calling it yourself is how
55
+ registers exactly this function, so every component's render ends up here; calling it yourself is how
47
56
  you draw into a plain node, which is the incremental-adoption path and the way to test a template
48
57
  without spinning up an element.
49
58
 
@@ -54,14 +63,28 @@ import { html } from '@verajs/core';
54
63
  renderInto(html`<p>${count}</p>`, document.querySelector('#app'));
55
64
  ```
56
65
 
57
- It **owns its own range and nothing else**: the first call anchors a root part at a marker it
58
- appends, later calls with the same container reuse that part and walk only the value slots, and
59
- whatever was already in the container stays. It is not reactive — call it again to update, or use a
60
- component and let a store do it.
61
-
62
- It was named `render` until 0.2.0, which collided with core's `render` — a different function, with
63
- a different arity, that declares a *reactive* template and commits a component's setup. Both are
64
- public and both are documented, so a reader who knew one misread the other.
66
+ It **owns its own range and nothing else**: the first call anchors a root part between two markers
67
+ it appends, later calls with the same container reuse that part and walk only the value slots, and
68
+ content before and after that range stays — whatever was already in the container, and whatever other
69
+ code (a script, a browser extension) appends to it later, survives every re-render, a template swap
70
+ included. It is not reactive — call it again to update, or use a component and let a store do it.
71
+
72
+ **A component's shadow root is different: by default its template owns it** (`foreignNodes: 'drop'`). Foreign nodes
73
+ — nodes placed in a component's root by anything other than its own template — are left alone by an ordinary
74
+ re-render, and cleared with everything else when the template changes (a different template, text, a list, nothing);
75
+ development says so the first time. The root then needs no marker comments, which makes every shadow component
76
+ cheaper to create. A component that must keep what something else puts in its root says
77
+ `init({ host: this, shadow: 'open', foreignNodes: 'preserve' }, setup)`; `wire([renderer({ foreignNodes: 'preserve' })])`
78
+ makes that every component's default. Either way it covers component roots only: a container handed to `renderInto`
79
+ (`document.body`, `#app`) always keeps foreign nodes, as above. A shadow root that already holds something at its first
80
+ render (a server's declarative root, styles' `<style>` fallback) keeps its markers too. Light-DOM component roots are
81
+ not affected yet. One corner: a `hold()` at an owned root parks the root's whole content with the branch it parks, so
82
+ a foreign node there goes away with that branch and comes back with it rather than being dropped — as with a plain
83
+ element whose whole content is one binding.
84
+
85
+ It was named `render` until 0.2.0, which collided with core's `render` of the time — a different function, with
86
+ a different arity, that declared a *reactive* template and committed a component's setup (a setup now returns its
87
+ render instead). Both were public and both were documented, so a reader who knew one misread the other.
65
88
 
66
89
  ## Bindings
67
90
 
@@ -74,12 +97,23 @@ public and both are documented, so a reader who knew one misread the other.
74
97
  | `<p ?hidden=${value}>` | boolean attribute, present when truthy |
75
98
  | `<input !checked=${value}>` | property written from the **live DOM** rather than from what the binding last wrote — see below |
76
99
  | `<button @click=${fn}>` | event listener. An object with a `handleEvent` method works too — `addEventListener` takes both |
77
- | `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital — a template-written `onclick` stays a plain attribute (yours, greppable); **spread refuses it** (see the spread section's security note) |
100
+ | `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital. A STATIC `onclick="…"` stays a plain attribute (yours, greppable); a BOUND `onclick=${…}` runs its value as code, so it is **refused** — in templates, in spread and on the server alike |
78
101
  | `<input ${fn}>` | element ref: a function is called with the element |
79
- | `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `ref()` works here |
102
+ | `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `signal()` works here |
80
103
  | `<input ${spread(props)}>` | names resolved at runtime — see [`/spread`](#verajsrendererspread) |
81
104
 
82
- A ref runs once per **distinct value**, not once per render.
105
+ A ref runs once per **distinct value**, not once per render — and **after its render pass**, once the
106
+ pass's DOM exists: the element is inserted, a custom element is upgraded, and it belongs to its own
107
+ document, so a ref can measure it, focus it, or read its window. Within a pass, refs run in commit order
108
+ — document pre-order, so an element's ref runs before the refs inside it and before its next sibling's —
109
+ after the pass's `<select>` values are set; a
110
+ ref replaced or removed before its turn is handed nothing. A ref runs **untracked**: what it reads never
111
+ subscribes the component that rendered it — a ref captures an element, it is not a dependency.
112
+
113
+ **Replacing a ref tells the old one first.** Changing `${a}` to `${b}` calls `a(null)` at once and hands `b`
114
+ the element after the pass; changing it to `${null}` calls `a(null)`. A `{ value }` ref is emptied the same way.
115
+ A value that applies itself (`_$apply$`, such as a spread) is never written to — it owns its own lifecycle,
116
+ so a position switching from a spread to a ref leaves the spread's keys as they were.
83
117
 
84
118
  **A ref is released when its subtree is rendered away, and not when its component is removed from
85
119
  the document.** Toggling `${show ? html`<i ${box}>` : 'gone'}` sets `box.value` back to `null` (and
@@ -98,6 +132,13 @@ object with no `handleEvent` — is inert, and **development names it at the bin
98
132
  only ever called when a user clicks, so left unchecked the mistake surfaces at a point where nothing
99
133
  on the stack says where the value came from.
100
134
 
135
+ **A handler never subscribes the hook that happens to be running.** An effect that fires an event
136
+ synchronously — `button.click()`, `input.focus()`, `dispatchEvent` — runs the handler inside itself, and
137
+ the handler's reads used to subscribe that effect: a handler doing `state.count++` re-ran the effect on
138
+ every later click. Every listener Vera binds — `@event`, spread's `@event` key, `data-vd-on-*` — runs
139
+ untracked. A listener you add yourself with `addEventListener` is outside Vera: fired synchronously from
140
+ inside a hook it still tracks, so read through `untrack()` there.
141
+
101
142
  ### `!name` — a live property
102
143
 
103
144
  Every other binding skips a write when the value matches what it last wrote. That is what keeps a
@@ -114,15 +155,27 @@ first binding still says `true`, still matches what it committed, and never writ
114
155
  and the page diverge and no amount of re-rendering reconciles them. A `<select>`'s options are the
115
156
  same shape.
116
157
 
158
+ A `<select>`'s selection is controlled however it is spelled — `.value`, `!value` or `.selectedIndex`, written
159
+ in the template or as a `spread()` key. Every binding on a select is committed when the render pass ends, so
160
+ its options exist whether they are static, a list, a nested template or a keyed list; the selection is re-asserted
161
+ on every render (its options can move under an unchanged value) and written only when the select holds a different
162
+ one (the write resets every option, so skipping it is what keeps a table with a select per row fast). On a
163
+ `<select multiple>`, `value` and `selectedIndex` each control ONE selection and a selection the user adds is kept;
164
+ bind `?selected=${…}` on each `<option>` to control every one. Development says so.
165
+
117
166
  It is deliberately narrow, and it is a **property** binding only:
118
167
 
119
168
  - **Not for text inputs.** Bind those with `.value` and let a person's typing stand. `!value` exists
120
169
  and is authoritative, which is precisely why it is not the default.
121
170
  - **Not offered for attributes or booleans.** Nothing changes those behind the renderer's back, so
122
171
  there is nothing to re-read.
123
- - **It yields during hydration.** A click that happened before the bundle landed had no handler to
124
- report it, so adoption records the value without writing; live semantics resume on the first
125
- state-driven render.
172
+ - **On a component it is delivered**, exactly as `.name` is: compared against the component's current
173
+ value on every render and, on a difference, handed to it — a running component re-renders. An equal
174
+ value costs one read and renders nothing.
175
+ - **It yields during hydration — for a control's user state.** A click that happened before the bundle
176
+ landed had no handler to report it, so adoption records `value`, `checked`, `selected` and `open`
177
+ without writing; live semantics resume on the first state-driven render. Any other `!name` is
178
+ written on adoption (`!indeterminate`, which no markup can carry), and on a component delivered.
126
179
 
127
180
  `spread({ '!checked': … })` means the same thing, and `@verajs/ssr` serializes it exactly as
128
181
  `.checked` — a server has nothing to re-read.
@@ -138,7 +191,8 @@ What a child position does with each kind of value. These match lit-html exactly
138
191
 
139
192
  | Value | Renders |
140
193
  | --- | --- |
141
- | string, number, `true`, `false`, `0` | as text — `${cond && 'x'}` puts the word `false` on the page |
194
+ | string, number, `0` | as text |
195
+ | `true`, `false` | as text — **and development says so**; see below |
142
196
  | `null`, `undefined` | nothing |
143
197
  | a template result | the template, updated in place while its shape holds |
144
198
  | an array or iterable | each entry in order; key them with `keyed()` |
@@ -148,6 +202,68 @@ What a child position does with each kind of value. These match lit-html exactly
148
202
  Strings render as **text**, always. There is no path by which an interpolated value becomes markup
149
203
  — see [Trusted HTML](#trusted-html-and-why-there-is-no-unsafehtml).
150
204
 
205
+ **An element whose whole content is one `${…}` belongs to that value.** `<ul>${rows}</ul>` renders its rows
206
+ straight into the `<ul>` with no marker nodes at all, so nodes added to that `<ul>` by other code are removed when
207
+ the value changes. Anywhere else a position is bracketed by two empty comments, and what sits outside them is
208
+ left alone. A custom element is never owned this way — a light-DOM component renders into its own children, so a
209
+ `${…}` inside `<my-panel>` keeps its markers and the two coexist.
210
+
211
+ ### A boolean child renders the word, and JSX is the exception
212
+
213
+ `${items.length > 0 && html\`…\`}` is the ordinary conditional idiom, and when the test fails the
214
+ whole expression is `false` — which renders the text **"false"** on the page. The value is
215
+ legitimate and nothing throws, so **development names it** at the binding rather than leaving it to
216
+ be found by looking at the page. Write the form that renders nothing:
217
+
218
+ ```js
219
+ html`<p>${cond ? html`<em>yes</em>` : null}</p>` // or: ${(cond && html`…`) || null}
220
+ ```
221
+
222
+ **In JSX the same code needs no change** — `@verajs/jsx` compiles a boolean child away, which is
223
+ React's rule and where React expectations live. That is the **one** value semantic on which JSX and
224
+ a hand-written template differ, and this warning is what meets JSX-shaped code pasted into a
225
+ template. `0` still renders in both, exactly as in React: the rule is about booleans, not falsiness.
226
+
227
+ ### A template committed into the wrong namespace is named
228
+
229
+ An `<svg>` draws SVG content and its three HTML integration points — `<foreignObject>`, `<desc>`
230
+ and `<title>` — and nothing else. A template written `` html`…` ``
231
+ and handed across a function boundary into one is still HTML — `<path>` parsed as HTML is an
232
+ `HTMLUnknownElement` with the right tag name and no geometry, so a whole set of icons can vanish
233
+ with nothing to search for:
234
+
235
+ ```js
236
+ const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
237
+ Frame(html`<path d="M0 0h24" />`); // silent: nothing draws
238
+ Frame(svg`<path d="M0 0h24" />`); // the fix — the tag is chosen where the template is WRITTEN
239
+ ```
240
+
241
+ The tag is right where it was written and the call site cannot know the destination — lit-html
242
+ behaves the same way. **Wire `@verajs/renderer/namespaces`** and the renderer corrects it: an
243
+ `` html`…` `` template is then parsed in the namespace of the position it lands in, so the first line
244
+ above draws too (see [below](#verajsrenderernamespaces--a-template-parsed-where-it-lands)).
245
+ Without it, **development names it**, once per host namespace, host name, content namespace and tag. HTML content gets both remedies: `` svg`…` `` when the element was
246
+ meant to be SVG, and an HTML island (`<foreignObject>` in SVG, `<mtext>` in MathML) when it is
247
+ genuinely HTML. Tagging a custom element `` svg`…` `` would silence the message and leave the
248
+ element permanently un-upgraded, since custom-element upgrade is spec-gated on the HTML namespace.
249
+
250
+ The rule is a namespace MISMATCH, so MathML committed into an `<svg>` and SVG committed into a
251
+ `<math>` are named by it too — with their own advice, since the template's tag is already right
252
+ there and only the destination is wrong. It is silent where the content is correct: inside
253
+ `<foreignObject>`, `<desc>` and `<title>`, inside MathML's token elements, inside
254
+ `<annotation-xml>` carrying an HTML `encoding` — or `image/svg+xml`, MathML's own registered
255
+ spelling for an SVG annotation — as an ATTRIBUTE, the only form the parser reads (an `.encoding`
256
+ property is named), for an `<svg>` in any `<annotation-xml>`, where the parser itself puts one, and
257
+ for `<style>`/`<script>`, which never draw — an HTML `<style>` inside an `<svg>` applies its rules
258
+ perfectly well.
259
+
260
+ **In JSX this cannot happen** unless it is switched off: `@verajs/jsx` wires
261
+ `@verajs/renderer/namespaces` from every file it compiles (not with `inject: false` or
262
+ `namespaces: false`, which leave it to you), so `<Frame><path /></Frame>` works. The message is what meets a hand-written template when
263
+ the module is not wired, or a template built before it was — the message names that too.
264
+
265
+ The whole check folds away in production — no code and no strings.
266
+
151
267
  A DOM node renders as itself, which is how a template holds something another library owns:
152
268
 
153
269
  ```js
@@ -167,9 +283,11 @@ renderInto(html`<ul>${rows.map((row) => keyed(row.id, html`<li>${row.label}</li>
167
283
  ```
168
284
 
169
285
  `keyed(key, result)` tags a result with its identity, so a reorder **moves** the existing elements
170
- instead of rebuilding them — focus, scroll position, form state and running animations all survive.
286
+ instead of rebuilding them — form state, scroll position and running animations survive. Focus does
287
+ not survive a MOVE: the platform blurs any node that is re-inserted, framework or not (pinned in the
288
+ browser suite), so only the elements that actually moved lose it.
171
289
  It is its own entry because most apps never reorder a list, and the algorithm that makes reordering
172
- cheap is <!--size:keyed.gzip-->923 B<!--/size:keyed.gzip--> gzipped they would otherwise carry. Importing `keyed` is the whole installation:
290
+ cheap is <!--size:keyed.gzip-->2.69 KB<!--/size:keyed.gzip--> gzipped they would otherwise carry. Importing `keyed` is the whole installation:
173
291
  nothing registers, and there is no `wire()` call — the marker stamps each result with the strategy
174
292
  that understands it, so a list always names its own reconciler and two strategies cannot disagree
175
293
  about one. Lit splits `repeat` out for the same reason; the difference is that this one arrives on
@@ -182,10 +300,28 @@ than at install. Both ship from this package and bump together, so a single vers
182
300
  the trap is pinning one and floating the other. `@verajs/renderer/spread` carries the same rule for
183
301
  the same reason.
184
302
 
185
- **It is additive, not a substitute.** Unlike `/hydrate` and `/profiler`, this entry imports nothing
303
+ **It is additive, not a substitute.** Unlike `/profiler`, this entry imports nothing
186
304
  at all — it reaches whatever renderer is present through a handful of mangling-exempt members — so
187
305
  it is safe alongside any of them, `/hydrate` included.
188
306
 
307
+ <!-- D28, 2026-11-12: the full-renderer requirement below lives HERE while lists is unreleased; llms.txt documents no
308
+ automatic lists yet, and its lists section must carry the same sentence when lists is released. -->
309
+ **Experimental: automatic `.map`, `lists` and `createSelector`.** With `lists` wired —
310
+ `wire([renderer, lists])` — a plain `state.rows.map((row) => html`…`)` over a store array inside a render is a keyed
311
+ list whose rows track themselves: a field write re-renders that one row, and pushes, removals and swaps touch only what
312
+ moved. Rows are keyed by an item's own `id`, else by the item itself. `lists` needs the FULL renderer: wired beside a
313
+ bare `{ on: 'render', fn: renderInto }` its rows cannot commit themselves, so every row's change re-renders the parent,
314
+ and development says so once (`lists-no-renderer`). `createSelector(() => state.selected)` returns
315
+ `isSelected(key)`, which re-renders only the old and the new key's rows on a change. Without `lists` wired, development says so once
316
+ (`lists-unwired`) when such a `.map` returns templates, since rows are then matched by position; to match by position on
317
+ purpose, map a plain copy, `[...state.rows].map(…)`. The copy still TRACKS — spreading reads every index, so the render
318
+ re-runs on any item change — it opts out of keying, not of reactivity. **Hydrated, an automatic list adopts the server's rows**
319
+ (their nodes, and a component row's element) instead of rebuilding them; a component row is handed its `.item` AFTER it
320
+ upgrades — its first render may see `undefined`, so read it as `this.item?.label`. Not released; the design is still
321
+ being measured. **A hidden list is released when the render that hid it returns**: a component's render, or a row's
322
+ own render for a list nested in a row. A `.map` inside your own render-priority hook (`effect(fn, { priority: 50 })`) is a list too,
323
+ but one it hides is released only when that hook is torn down.
324
+
189
325
  **A list is keyed because `keyed()` marked it, not because its results have a `key` property.**
190
326
  Setting `.key` by hand no longer makes a list keyed — the marker is what carries the algorithm, so
191
327
  it is what the renderer looks for, on the client and when adopting server markup alike.
@@ -196,6 +332,9 @@ unkeyed item in a keyed list has no identity to match on.
196
332
  An unkeyed list is not wrong — it updates each position in place, which is exactly right for a list
197
333
  whose order never changes.
198
334
 
335
+ One position can switch between a keyed and an unkeyed list, in either direction, and render
336
+ correctly — the items are the same kind of thing, and an unkeyed one simply has no key to match on.
337
+
199
338
  ## Preserving DOM — `hold()`
200
339
 
201
340
  ```js
@@ -214,7 +353,9 @@ parked, `0` on return, and `0` even for a node moved directly between two attach
214
353
  applier does with the nodes can hold it, and lit's `cache()` cannot either. If a scroll position
215
354
  matters, read it before the toggle and restore it after.
216
355
 
217
- Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write.
356
+ Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write, and the editor is rebuilt when it returns: parking happens only when another held template takes its place.
357
+
358
+ **A parked template's refs keep their element** — parking is not destruction, and the element comes back. They are released when the section itself goes away, along with everything it parked; clearing the section (`null`) keeps what it parked.
218
359
 
219
360
  It only re-adopts a template it has seen at **that same call site** — two `hold()` calls in
220
361
  different templates are two different templates, and neither adopts the other's DOM. The other
@@ -260,22 +401,306 @@ committed in place against templates that replaced a different template.
260
401
  | Import | What it adds | Ships in production |
261
402
  | --- | --- | --- |
262
403
  | `@verajs/renderer` | the renderer | yes |
263
- | `@verajs/renderer/hydrate` | a superset whose first render adopts server-rendered DOM | yes |
404
+ | `@verajs/renderer/hydration` | `hydration` (wire it beside the renderer) — the first render adopts server-rendered DOM | yes |
405
+ | `@verajs/renderer/hydrate-slots` | `hydrateSlots` (wire it) — reads the server's light-slot format, for an app that hydrates light slots | yes |
264
406
  | `@verajs/renderer/keyed` | `keyed(key, result)` — keyed list reconciliation | yes |
265
407
  | `@verajs/renderer/spread` | `spread(props)` — binding names resolved at runtime | yes |
266
408
  | `@verajs/renderer/tag` | `` tag`h1` `` — an element whose tag name is decided at runtime | yes |
267
409
  | `@verajs/renderer/slots` | `slots` (wire it) + `slotted(host, name?)` — light-DOM `<slot>` distribution | yes |
410
+ | `@verajs/renderer/namespaces` | `namespaces` (wire it) — an `html` template parsed in the namespace of where it lands | yes |
411
+ | `@verajs/renderer/elements` | `elements` (wire it) — behavior attached to claimed elements in templates, mounted and unmounted with their instances | yes |
412
+ | `@verajs/renderer/portal` | `portal(target, template)` — a component draws into ANOTHER element (a modal on `document.body`), in a range of its own | yes |
413
+ | `@verajs/renderer/until` | `until(promise, fallback)` — a promise at a child position: the fallback, then its value | yes |
414
+ | `@verajs/renderer/native-elements` | `nativeElements` (wire it) — `init` on a built-in element (a `div`, a `section`…) with a custom element's lifecycle | yes |
415
+ | `@verajs/renderer/multi-window` | `multiWindow` (wire it) — components left in a pop-out or an iframe are released when that window closes | yes |
268
416
  | `@verajs/renderer/profiler` | a superset that measures template churn | no — development only |
269
417
 
270
- `/hydrate` and `/profiler` each re-export the whole public API, so they are drop-in replacements for
271
- the base import. **Never mix two of them in one app** — that loads two renderers with two template
272
- caches.
418
+ `/profiler` re-exports the whole public API, so it is a drop-in replacement for the base import. **Never mix it
419
+ with `@verajs/renderer` in one app** — that loads two renderers with two template caches, and profiling while
420
+ rendering through the other observes an instance nothing renders into (measured: renders reported zero frames while
421
+ the page updated correctly). `formatReport` says so when it observed nothing, because a zero report is otherwise
422
+ indistinguishable from an app with nothing to optimize. **A hydrating app profiles like any other:** wire
423
+ `hydration` beside the profiler's renderer — `wire([renderer, hydration])` with `renderer` from
424
+ `@verajs/renderer/profiler` — and its adoption is profiled too.
425
+
426
+ ## `@verajs/renderer/elements` — behavior on elements in templates
427
+
428
+ Attach behavior to elements *in templates* — "every `[autofocus]`", "every `<slot>`", "every
429
+ `<dialog open>`" — without a directive system and without touching the elements' markup. A
430
+ **claimant** is an ordinary insert on `'element'`: it is asked about each element of a template once,
431
+ when the template is first used, and answers with a shared behavior object or `undefined`. Every
432
+ instance of that template then runs the behavior's `mount` once its render has finished, and
433
+ `unmount` at teardown with whatever `mount` returned.
434
+
435
+ The example is a real gap. Measured on Chromium, Firefox and WebKit, the first `autofocus` element
436
+ rendered after page load takes focus and **every later one is ignored** — so the second form an app
437
+ shows, an edit dialog or a step two, never gets the focus its markup asks for. Five lines fix it:
438
+
439
+ <!-- recipe -->
440
+ ```js
441
+ import { wire, html } from '@verajs/core';
442
+ import { renderer, renderInto } from '@verajs/renderer';
443
+ import { elements } from '@verajs/renderer/elements';
444
+
445
+ /** One shared object for every claimed element of every instance. */
446
+ const autofocus = { mount: (element) => element.focus() };
447
+
448
+ wire([
449
+ renderer,
450
+ elements,
451
+ { on: 'element', fn: (el) => (el.hasAttribute('autofocus') ? autofocus : undefined), priority: 50 },
452
+ ]);
453
+
454
+ const step = (n) => html`<form><label>Step ${n} <input autofocus name=${'step' + n}></label></form>`;
455
+ const [first, second] = [document.createElement('div'), document.createElement('div')];
456
+ document.body.append(first, second);
457
+ renderInto(step(1), first);
458
+ document.activeElement.blur();
459
+ renderInto(step(2), second); // a second form, later: focused, where the platform alone would not
460
+ if (document.activeElement.name !== 'step2') throw new Error('the second form did not take focus');
461
+ ```
462
+
463
+ What a claimant can rely on:
464
+
465
+ - **It is asked about the TEMPLATE's element, once.** The element is inert: its tag and its
466
+ **static** attributes are real, bindings are not applied yet — `autofocus=${x}` cannot be claimed on
467
+ `x`. Claim the attribute's presence and decide in `mount`. SVG and MathML elements are asked too.
468
+ - **`create(element, adopted)` runs as each instance is created** — before its first update writes
469
+ anything, and before the instance is connected anywhere — so the element holds exactly the static
470
+ children the template wrote, each binding position still the empty text it parsed as. It is the one
471
+ moment those can be told apart; `@verajs/renderer/slots` records a host's static children there.
472
+ Nothing is kept from it, and it is optional.
473
+ - **`mount(element, { root, adopted })` runs once the render that created the instance has
474
+ finished** — in the same end-of-render pass as refs, in document order, so a claim that MOVES an
475
+ element does so after refs above it saw it in place (measure in `mount`, not in a ref) — so the whole tree is in place and connected if its container is — a nested instance is
476
+ inserted only when its outer one is, which is why it does not run straight after the instance's own
477
+ update. `root` is the render's container. An instance discarded before its render ends never mounts.
478
+ - **`unmount(kept, element)` runs once, at teardown** — a template swapped out, a keyed row dropped, a
479
+ list shrunk, a container cleared — and only when `mount` returned something. **`hold()` is not
480
+ teardown**: a parked instance keeps its mount and is not mounted again when it returns.
481
+ - **Several claimants may claim one element**; each gets its own `create`/`mount`/`unmount`, in wire order.
482
+ - **No updates.** A behavior that must react to values is a binding or an applier (`_$apply$`), not a
483
+ claim — which is what keeps claims off the hot path.
484
+ - **A throwing `create`, `mount` or `unmount` is reported, never raised** — the rule a `&ref` follows:
485
+ to the app's `'error'` chain with the component, else as uncaught (`reportError`), and the render,
486
+ the other claims and the teardown carry on. Every throw is reported. A claim whose `create` threw is
487
+ dropped for that instance — it never mounts or unmounts — and its element stays as the template
488
+ built it.
489
+ - **Wire it before anything renders**, like `slots`: a template asks its claimants when it is first
490
+ used, and a claimant wired later never hears about templates already built — development says so
491
+ at `wire`, for this module and every other that decides per template (`namespaces`, `slots`). An app that wires no
492
+ claimant pays nothing; one that does pays one walk per new template, and one short walk per
493
+ instance of a template something claimed.
494
+
495
+ ## `@verajs/renderer/until` — a promise in a template
496
+
497
+ ```js
498
+ import { until } from '@verajs/renderer/until';
499
+
500
+ define('x-user', () => {
501
+ const user = fetchUser(); // made ONCE, in the setup
502
+ return () => html`<p>${until(user, html`<em>loading…</em>`)}</p>`;
503
+ });
504
+ ```
505
+
506
+ It shows the fallback, then what the promise resolves to.
507
+
508
+ - **The same promise again** (any re-render) keeps what is shown: no flash, no second subscription. Make the promise in
509
+ the setup, as above; one written inline in the template is a new promise, a new request, every render.
510
+ - **A new promise** shows the fallback again, and the old one's late answer is dropped, so a slow first request never
511
+ overwrites a newer one.
512
+ - **Removed before it settles,** the answer is dropped.
513
+ - **Not a promise:** shown at once.
514
+ - **A rejection** keeps the fallback, and the browser reports it, as any unhandled rejection: in the console with its
515
+ stack, and as an `unhandledrejection` event, which error monitoring hears. To SHOW an error, pass the caught promise —
516
+ a caught promise resolves to whatever the handler returns:
517
+
518
+ ```js
519
+ html`<p>${until(user.catch(() => html`<b>couldn't load</b>`), html`<em>loading…</em>`)}</p>`
520
+ ```
521
+
522
+ That also keeps the browser from reporting an error you handled. For a refreshing state too, use `resource()` from
523
+ `@verajs/store/resource`, which carries `loading`, `value` and `error`.
524
+ - **On a server** it renders the fallback and waits for nothing, and a rejection there is consumed: the server never shows
525
+ the result, and an unhandled rejection would end a Node process. Hydration draws the fallback again and the value
526
+ replaces it.
527
+
528
+ `until` is built on the `_$child$` protocol below; core and the renderer carry nothing for it.
529
+
530
+ ## `@verajs/renderer/multi-window` — components in the windows your page opens
531
+
532
+ A component moved into another window's document — a pop-out (`window.open`) or an iframe — is kept by core, state and
533
+ all, and comes back the same way. When that window CLOSES with components still inside, nothing tells them: they stay
534
+ subscribed to this window's stores, alive and running, for the life of the page. Wire `multiWindow` and they are
535
+ released then:
536
+
537
+ ```js
538
+ import { wire } from '@verajs/core';
539
+ import { renderer } from '@verajs/renderer';
540
+ import { multiWindow } from '@verajs/renderer/multi-window';
541
+
542
+ wire([renderer, multiWindow]);
543
+
544
+ const popup = window.open('', 'panel');
545
+ popup.document.body.append(panel); // pop out: kept
546
+ popup.addEventListener('pagehide', () => document.body.append(panel)); // optional: bring it home as it closes
547
+ ```
548
+
549
+ - **What is released:** every component of this core still in the closed window's document, shadow roots included —
550
+ one moved there, one built there while it was out, one appended there directly. Each runs its cleanups once, and no
551
+ write wakes it again.
552
+ - **When:** at that window's final `pagehide`, on this window's NEXT task, so your own `pagehide` handler runs first; a
553
+ panel it moves home is no longer in the closed document and survives.
554
+ - **Not released:** a back/forward-cached hide (`persisted`), which can come back.
555
+ - **Cost:** nothing on any normal path (core hears a move into another document on its cold cross-window path only), and
556
+ nothing at all for an app that does not wire it. It imports nothing.
557
+
558
+ In the platform's words: a `window.open` window is an *auxiliary browsing context*, an iframe's a *child navigable*,
559
+ moving a node into another document is *adoption* (core's `'adopted'` insert point), and a closing window's document is
560
+ *unloaded*.
561
+
562
+ ## `@verajs/renderer/native-elements` — `init` on a built-in element
563
+
564
+ A custom element tells core when it leaves the page and when it comes back — its `connectedCallback` and
565
+ `disconnectedCallback` — so a component that calls `init(this)` there is torn down when it is removed, set up again when
566
+ it returns, and kept when it is merely moved. A built-in element (a `div`, a `section`) given to `init` tells nobody: by
567
+ itself it is drawn and stays reactive, but it is never released when removed. Wire `nativeElements` and it gets exactly
568
+ the custom element's lifecycle. (Not to be confused with `@verajs/renderer/elements`, above, which attaches behavior to
569
+ elements *inside* templates.)
570
+
571
+ <!-- recipe -->
572
+ ```js
573
+ import { wire, init, html, createStore } from '@verajs/core';
574
+ import { renderer } from '@verajs/renderer';
575
+ import { nativeElements } from '@verajs/renderer/native-elements';
576
+
577
+ wire([renderer, nativeElements]);
578
+
579
+ const state = createStore({ count: 0 });
580
+ const panel = document.createElement('section');
581
+ document.body.append(panel);
582
+ init(panel, () => () => html`<button @click=${() => state.count++}>${state.count}</button>`);
583
+
584
+ panel.remove(); // torn down: its effects' cleanups run, it leaves every store
585
+ document.body.append(panel); // set up again, fresh — as a custom element re-added
586
+ ```
587
+
588
+ - **Removed:** torn down, exactly as a custom element's removal (cleanups run, nothing it read keeps it alive).
589
+ - **Re-attached:** set up again — its setup runs again, so what the setup created starts fresh.
590
+ - **Moved** in one operation (`append`/`insertBefore` of a connected element), or **into another window's document** (a
591
+ popped-out panel): kept, with its state.
592
+ - **Given `init` before it is on the page:** its setup waits for its first connect, as a custom element's does — a host
593
+ built off the page and never attached is never set up and holds nothing.
273
594
 
274
- **Which means an app can have one of them, not both — so a hydrating app cannot be profiled.** They
275
- each bundle their own renderer with its own instrumentation hook, so profiling while rendering
276
- through `/hydrate` observes an instance nothing renders into: measured, three renders reported zero
277
- frames while the page updated correctly. `formatReport` says so when it observed nothing, because a
278
- zero report is otherwise indistinguishable from an app with nothing to optimise.
595
+ **For a few hosts, not for volume:** a built-in host carries a little more than a custom element (its closed root and two
596
+ small nodes), so it costs a little more to create and to collect. Use it for the handful of roots, islands and panels
597
+ an app has; anything created in volume — rows, items, repeated widgets — belongs in a custom element.
598
+
599
+ **How it hears:** each host gets a CLOSED shadow root holding a default `<slot>` (its light content renders exactly as
600
+ before) and a tiny custom element whose own callbacks fire when its host is attached, moved or removed — the same in
601
+ Chromium, Firefox and WebKit. The root is closed, so `host.shadowRoot` stays `null` and selectors see the host's children
602
+ as before.
603
+
604
+ **Not supported** (said by name in development; the element still renders, and is never released when removed):
605
+
606
+ - elements that cannot hold a shadow root — `ul`, `li`, `table`, `button` and the rest; supported are `div`, `section`,
607
+ `article`, `aside`, `header`, `footer`, `main`, `nav`, `p`, `span`, `blockquote`, `h1`–`h6` and `body`;
608
+ - an element that already has a shadow root — including one `init` attached from a `shadow` option, or from the app's
609
+ `renderer({ shadow })` default (an app with a shadow default has no supported built-in hosts);
610
+ - the host's own later `attachShadow()` (or declarative shadow DOM) — it now has one; development says why.
611
+
612
+ One thing changes for a supported host: a DIRECT child carrying a `slot` attribute (`<span slot="title">`) renders
613
+ nowhere, since the host's root has only a default `<slot>` (the same in every engine; a deeper descendant with one is
614
+ unaffected) — development says so, naming the host. Document CSS is otherwise unaffected — child and structural selectors, `:empty`, `:has()`, inheritance
615
+ and layout match a host without it.
616
+
617
+ Also: a built-in element built in a document with no window (`document.implementation.createHTMLDocument`, a
618
+ `DOMParser` result) is not set up; and a component left inside a window when that window closes (an iframe removed, a
619
+ pop-out closed, with the component still in it) is the app's to remove.
620
+
621
+ ## `@verajs/renderer/portal` — drawing into another element
622
+
623
+ A component's own render goes into its own root. To draw somewhere ELSE — a modal or a toast on `document.body`, a
624
+ tooltip in an overlay layer — call `portal(target, template)` in its setup:
625
+
626
+ <!-- recipe -->
627
+ ```js
628
+ import { wire, define, html, createStore } from '@verajs/core';
629
+ import { renderer } from '@verajs/renderer';
630
+ import { portal } from '@verajs/renderer/portal';
631
+
632
+ wire([renderer]);
633
+
634
+ const state = createStore({ open: true, title: 'Saved' });
635
+ define('x-toast', () => {
636
+ portal(document.body, () => (state.open ? html`<div role="status">${state.title}</div>` : ''));
637
+ return () => html`<button @click=${() => (state.open = !state.open)}>toggle</button>`;
638
+ });
639
+
640
+ const toast = document.createElement('x-toast');
641
+ document.body.append(toast); // the button in the component, the status line at the end of <body>
642
+ toast.remove(); // the status line goes with it
643
+ ```
644
+
645
+ - **A range of its own.** It appends two comment markers to `target` and draws between them, so any number of portals
646
+ share one target and none touches what was there before it.
647
+ - **The render's slot.** It is drawn when the component's render is (a keyed `.map` keeps its rows with their items, and
648
+ layout effects see it drawn), it updates from what it reads like any render, and what a draw made and no longer
649
+ reaches — a hidden automatic list, a computed — is released as a render's is.
650
+ - **Owned by the component.** Removing the component takes its content and its markers out of `target`; a component
651
+ that `persist`s takes them out while it is away and draws them again when it is back — appended at the END of
652
+ `target` again, so its order among the target's other children (two open modals) can change. Moving the component into
653
+ another window's document (a pop-out) leaves the portal where it is — `target` is where it was asked to draw — and it
654
+ stays live.
655
+ - **Light DOM.** It draws into `target` itself, never into a shadow root: into a shadow host, the content is the host's
656
+ light content, placed by its `<slot>`. Styles are therefore `target`'s, not the component's — a shadow component's
657
+ `static styles` do not reach a portal's content (style it in the document, or with its own `<style>`). Events bubble
658
+ from the content up through `target`'s ancestors, not through the component.
659
+ - **The client only.** On a server a portal registers nothing: the server renders the component's own template, and
660
+ hydration adopts that and then draws the portal once.
661
+ - **Call it in a setup.** It belongs to the component being set up; after an `await` in an async setup none is, and it
662
+ throws, as `effect` does (`no-owner`).
663
+
664
+ It keeps `@verajs/core` external in every build (its draw is one of core's effects; inlined, it would be a second core),
665
+ so a CDN page's import map names `@verajs/core` beside it — as it already does for `@verajs/store`.
666
+
667
+ ## `@verajs/renderer/namespaces` — a template parsed where it lands
668
+
669
+ A template's namespace is normally fixed by its tag: `` html`…` `` is HTML wherever it goes, which is
670
+ why a shape handed into an `<svg>` needs `` svg`…` ``. Wire this module and the renderer instead
671
+ parses an `html` template **in the namespace of the position it is committed into** — the way the
672
+ browser's own parser treats markup written inside an `<svg>`:
673
+
674
+ <!-- recipe -->
675
+ ```js
676
+ import { html, wire } from '@verajs/core';
677
+ import { renderer, renderInto } from '@verajs/renderer';
678
+ import { namespaces } from '@verajs/renderer/namespaces';
679
+
680
+ wire([renderer, namespaces]);
681
+
682
+ const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
683
+ const host = document.createElement('div');
684
+ renderInto(Frame([html`<title>Close</title>`, html`<path d="M0 0h24"></path>`]), host);
685
+
686
+ if (host.querySelector('path').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
687
+ if (host.querySelector('title').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
688
+ ```
689
+
690
+ The answer comes from the parser, not from a list: SVG's camelCase names keep their case,
691
+ `<foreignObject>`, `<desc>` and `<title>` hold HTML again, MathML's token elements likewise, and the
692
+ same strings committed into a `<div>` stay HTML. Under a MathML parent the parser's answer depends on
693
+ the child as well — `<svg>` inside `<annotation-xml>`, `<mglyph>` inside `<mi>` — so there it is asked
694
+ with the template's own first tag.
695
+
696
+ - **`@verajs/jsx` wires it for you**, from every file it compiles — JSX cannot write `` svg`…` ``.
697
+ - **Wire it before anything renders.** It applies to a template when the template is first built, so
698
+ one built earlier keeps the namespace it was built in; development names that case.
699
+ - **`svg`/`mathml` tags still work** and still decide their own namespace — wiring this changes only
700
+ `html` templates.
701
+ - **What it costs**: its own bundle, only when wired. The renderer's update path is untouched; a
702
+ template is resolved once per instance it creates, measured at parity with explicit tags on
703
+ Chromium, Firefox and WebKit.
279
704
 
280
705
  ## `@verajs/renderer/slots` — light-DOM slots
281
706
 
@@ -301,7 +726,7 @@ Given this markup:
301
726
 
302
727
  <!-- recipe -->
303
728
  ```js
304
- import { init, render, wire, html } from '@verajs/core';
729
+ import { init, wire, html } from '@verajs/core';
305
730
  import { renderer } from '@verajs/renderer';
306
731
  import { slots, slotted } from '@verajs/renderer/slots';
307
732
 
@@ -311,13 +736,10 @@ customElements.define(
311
736
  'my-card',
312
737
  class extends HTMLElement {
313
738
  connectedCallback() {
314
- init(this); // LIGHT DOM — no shadow options
315
- render(
316
- () => html`<article>
739
+ init(this, () => () => html`<article>
317
740
  <header><slot name="header" @slotchange=${(e) => this.onHeader(e.target)}>Untitled</slot></header>
318
741
  <main><slot>Nothing here yet.</slot></main>
319
- </article>`
320
- );
742
+ </article>`); // LIGHT DOM — no shadow option
321
743
  }
322
744
  /** Written exactly as it would be against a shadow root, and it runs in both. */
323
745
  onHeader(slot) {
@@ -346,9 +768,38 @@ console.log(slotted(card, 'header').length); // 1
346
768
  > DIFFERENT renderer — lit-html — where there is no seam to find.) The assignment follows
347
769
  the platform's own rules — elements to the slot their `slot` attribute names, text to the default
348
770
  slot, fallback shown only while a slot is unassigned and restored when it empties, direct children
349
- only. Live: appending, removing, or re-slotting children redistributes automatically, with one documented
350
- divergence — see **Late children** below. Re-renders leave slotted nodes in place, identity intact, so focus and input values
351
- survive; SSR emits already-distributed markup and hydration adopts it.
771
+ only. **Every node goes to the slot its own `slot` names** — including the nodes a binding in the
772
+ page's template writes, so ``${items.map((i) => html`<li slot=${i.where}>…</li>`)}`` distributes
773
+ exactly as the same markup written out by hand, and keeps doing so as the list changes. Live:
774
+ appending, removing, or re-slotting children redistributes automatically. Re-renders leave slotted
775
+ nodes in place, identity intact, so focus and input values survive.
776
+
777
+ **Server-rendered and hydrated.** `@verajs/ssr` emits already-distributed markup — each filled slot's
778
+ content between two comments, exactly as this module leaves it on the client — and states the light
779
+ tree on each host. A hydrating page adopts it in place, nested components included, with one more
780
+ module wired, which only an app that hydrates light slots loads:
781
+
782
+ ```js
783
+ import { hydrateSlots } from '@verajs/renderer/hydrate-slots';
784
+ wire([renderer, hydration, slots, hydrateSlots]);
785
+ ```
786
+
787
+ Without it, a server-rendered host with light content is left exactly as served — never cleared — and the console
788
+ names what to wire (`hydration-slots`); a host the server stated empty (`1:`) hydrates without it.
789
+ **Wire `slots` on the server too:** a server without it writes no light-tree statement, so every
790
+ component it rendered is taken for client-made and renders fresh on the client — its server markup kept, hidden, as
791
+ unassigned light content — and no warning is possible, because the client cannot tell the two apart. **Serve the server's HTML unmodified, comments included:** a
792
+ minifier that strips comments removes the slots' markers, and the host renders fresh, as React, Lit
793
+ and Solid treat a missing marker. The light-tree statement carries a format number, so render and
794
+ hydrate with matching releases of `@verajs/ssr` and `@verajs/renderer`: a page in another format
795
+ renders fresh, its content kept, and the warning says so. A component host carrying no statement was
796
+ made on the client, and gets a client first render rather than an adoption.
797
+
798
+ **Measured, including where it still differs.** `tests/browser/slots-conformance.test.js` runs whole
799
+ component lifecycles through a real shadow root and through this module on Chromium, Firefox and
800
+ WebKit, comparing the composed tree and element identity after every step, and every scenario
801
+ matches — slot forwarding (a `<slot>` placed inside another light component shows what the outer slot
802
+ shows) and `hold()` inside content one template places into another component included.
352
803
 
353
804
  **A `<slot>` inside another slot's fallback works**, and takes over at the moment that fallback
354
805
  becomes visible — the same thing the platform does, verified by layout on three engines. Slots are
@@ -372,18 +823,17 @@ it work would mean writing framework attributes into the user's own markup.
372
823
 
373
824
  **A node added AFTER the first render joins its slot with full native semantics** — bare text and
374
825
  attribute-less elements included, in document order, exactly as a shadow root would assign them.
375
- The renderer stamps everything it emits at a light host's top level with a hidden, non-enumerable
376
- property, so an unstamped node there is knowably the user's; `slot=""`/`slot="name"` still route,
377
- they are simply no longer required.
378
-
379
- This used to be the feature's one documented divergence, and the rule existed because a light
380
- host's children after the first render are also the component's own rendered output, with nothing
381
- in the DOM to tell them apart. Ownership is written down now rather than inferred from position,
382
- so the ambiguity — and the rule — are gone. Two things remain worth knowing: whitespace appended
383
- to a light host suppresses the default fallback, which is parity (a shadow root does the same), and
384
- re-slotting a node (`slot="a"` → `"b"`) rejoins in light-tree order rather than arrival order.
385
- Every position you can reach orders exactly as the platform does — what light has fewer of is
386
- positions you can name, since a distributed child is no longer a direct child of the host.
826
+ A light host's own render occupies one range of its children, bracketed by the renderer's own
827
+ comments, so a node added outside that range is knowably the user's: added before it, it joins
828
+ ahead of everything the host was given; after it, behind. `slot=""`/`slot="name"` still route, they
829
+ are simply not required. Inside a slot, use `before()`/`after()` on what is already there (see
830
+ below) and the new node joins at that place in light order.
831
+
832
+ Two things are worth knowing: whitespace appended to a light host suppresses the default fallback,
833
+ which is parity (a shadow root does the same), and re-slotting a node (`slot="a"` → `"b"`) rejoins
834
+ in light-tree order rather than arrival order. Every position you can reach orders exactly as the
835
+ platform does — what light has fewer of is positions you can name, since a distributed child is no
836
+ longer a direct child of the host.
387
837
 
388
838
  **Cloning a RENDERED light component does not work, and cannot.** `cloneNode(true)` copies a
389
839
  light host's children — which after a render are the component's own output with the user's slotted
@@ -392,26 +842,46 @@ rendered tree ends up nested inside its own default slot. A shadow component clo
392
842
  opposite reason: `cloneNode` does not copy a shadow root, so the clone re-renders and its light
393
843
  children are still just its light children.
394
844
 
395
- Nothing can detect this — the ambiguity is the same one behind the late-children rule above, and
396
- the original user content was consumed at the first render, so there is nothing to recover. **To
397
- duplicate a component, clone the SOURCE markup and let the copy render itself**, rather than cloning
398
- a live instance. This matters most to anything that duplicates components as an operation: an editor
845
+ Nothing can detect this — after a render the user's content and the component's output are the
846
+ same kind of node in the same tree, and the original user content was consumed at the first render,
847
+ so there is nothing to recover. **To duplicate a component, clone the SOURCE markup and let the copy
848
+ render itself**, rather than cloning a live instance. This matters most to anything that duplicates components as an operation: an editor
399
849
  canvas, a repeater, a drag-to-copy.
400
850
 
401
851
  **`slotted(host, name?)`** is the component-internal accessor — what the user assigned to a slot,
402
852
  answered identically in shadow mode (native assignment) and light mode (the capture map). Omit
403
853
  `name` for the default slot. Component authors reach for this; app users do not.
404
854
 
855
+ **When the assignment is current.** Whatever a template does is distributed by the end of that render — an outer
856
+ template changing a component's children included — so code measuring slotted content right after a render (a layout
857
+ effect, `getBoundingClientRect`) sees the new assignment. A light host changed directly by your code
858
+ (`host.append(node)`, `node.slot = 'x'`) is redistributed by the next microtask, or at once when its slotted content is
859
+ read through the slots API (`slotted()`, `slot.assignedNodes()`).
860
+
861
+ ### Where the `<slot>` element is
862
+
863
+ **A slot with content steps out of the page, and its content stands in its place. A slot with
864
+ nothing assigned stays in the page, showing its fallback.** So the rendered tree reads the way the
865
+ composed tree of a shadow root reads: where a slot has content, that content is a child of the
866
+ slot's parent; where it has none, the fallback is the `<slot>` element's own children, and the
867
+ HTML standard's UA stylesheet gives every `<slot>` `display: contents`, so the element itself adds no
868
+ box. The switch happens each time a slot gains its first node or loses its last one.
869
+
870
+ Two things follow. `querySelector('slot')` finds exactly the slots currently showing their
871
+ fallback, and none that have content — so reach a slot through `&ref` or `event.target`, never by
872
+ selector. And a structural selector written against your template (`:first-child`, `> h2`) sees the
873
+ slotted content where a filled slot stood, which is where a reader sees it.
874
+
405
875
  ### The `<slot>` element is still the component's handle on the slot
406
876
 
407
877
  A slot is not only a position, and a component that keeps up with what it was given binds to the
408
878
  element itself. All of that means here what it means in a shadow root:
409
879
 
410
880
  ```js
411
- render(() => html`<header>
881
+ return () => html`<header>
412
882
  <slot name=${section} &ref=${(el) => (this.slot = el)}
413
883
  @slotchange=${(e) => wire(e.target.assignedElements())}>Nothing yet</slot>
414
- </header>`);
884
+ </header>`;
415
885
  ```
416
886
 
417
887
  - **`@slotchange`** fires on first assignment and on every change after it — and only then, so a
@@ -419,15 +889,38 @@ render(() => html`<header>
419
889
  `assignedNodes()` are asserted against real shadow DOM, which is the oracle for this. It fires
420
890
  for a slot whose rendering is currently displaced too (assignment is independent of rendering),
421
891
  exactly as native does for a slot that is not on screen.
422
- - **`node.assignedSlot` answers `null` — ask the slot, not the node.** The reverse lookup is a
423
- platform accessor tied to real shadow assignment, and overriding it on YOUR nodes is an intrusion
424
- this module refuses. The forward reads carry the same fact: `slot.assignedNodes().includes(node)`
425
- through a `&ref`, or `slotted(host, name)` from outside.
426
- - **Bind `slotchange` directly — it does not bubble to the host.** In a shadow root one listener on
427
- the root hears every slot by bubbling; here the slot handles are deliberately out of the document,
428
- so there is no tree for the event to climb and `host.addEventListener('slotchange', …)` hears
429
- silence. Use `@slotchange` on each slot, which also hands you the right `event.target`. (The same
430
- boundary as `querySelector('slot')`: fewer places to listen, not fewer events.)
892
+ - **`node.assignedSlot` answers light slots too.** The platform's getter knows only shadow roots, so slots replaces it
893
+ once per window, at that window's first light host. It answers for the nodes slots placed, from what distribution
894
+ already records (nothing is written per node), and defers to the getter it replaced for every other node, so
895
+ shadow-DOM nodes, other copies of Vera, and other code that patched it answer as before. One case stays native: a node
896
+ created in another window (an iframe's parent) and placed into a light host here reads `null` unless its own window
897
+ also has a light host. The forward reads carry the same fact: `slot.assignedNodes()` through a `&ref`, or
898
+ `slotted(host, name)` from outside.
899
+ - **Only a component that needs slotting pays for it.** One with no light content and no `<slot>` gets no observer and
900
+ no hidden element; a component is observed from its first `<slot>`. So a child appended by hand to a component that
901
+ has neither shows until a slot renders — native hides it. `observeSlots: 'eager'` observes a component
902
+ from its first render instead — `init({ host: this, observeSlots: 'eager' }, setup)` — as a shadow root follows
903
+ every host; `wire([renderer, slots({ observeSlots: 'eager' })])` makes that every light component's default (its own
904
+ `observeSlots` wins), at an observer per component. The default, `'lazy'` (paired as HTML's `loading` pairs them),
905
+ starts at the first `<slot>` or light child and is fully correct for everything a template renders. A value it does
906
+ not have reads as `'lazy'` — the built-in default, even where the app's is `'eager'`, as `foreignNodes` does — and
907
+ development says so.
908
+ - **A component you remove by hand and put back follows the hand-edit rule.** What its outer template then writes into
909
+ it is distributed by the component's own observer, a microtask later, not by the end of that template's render; the
910
+ slots API reads it at once (it flushes), and a direct DOM read in the same task can still see the old content.
911
+ - **A `<slot>` removed by hand unassigns its content, as in a shadow root.** Its content shows in the next slot of that
912
+ name, or nowhere: through the slot's own `remove()` / `replaceWith()`, or by removing its parent or an ancestor (a
913
+ microtask later, the hand-edit rule). One spelling cannot work: a slot WITH content has stepped out of the page (its
914
+ region stands in its place), so `slot.parentNode` is `null` and `parentNode.removeChild(slot)` has nothing to call.
915
+ - **Insert `<slot>`s through the template, or observe the component eagerly.** On a component observed lazily (the
916
+ default), a `<slot>` inserted by hand is not one the template rendered, so it stays empty, where a shadow root uses it
917
+ at once. With `observeSlots: 'eager'` it is claimed like the template's own. Rendering the slot conditionally
918
+ (`${open ? html`<slot></slot>` : null}`) works in every mode.
919
+ - **Bind `slotchange` directly — do not count on it reaching the host.** In a shadow root one listener
920
+ on the root hears every slot by bubbling. Here a slot with content is out of the document, so the
921
+ event fired as it fills has no tree to climb, while the one fired as it empties — the slot is back
922
+ in the page by then — does climb: a host-level listener hears some changes and not others. Use
923
+ `@slotchange` on each slot, which hears all of them and hands you the right `event.target`.
431
924
  - **`assignedNodes(options)` / `assignedElements(options)`** answer from the live assignment,
432
925
  through `event.target` or a `&ref`. With nothing assigned, `{ flatten: true }` gives the fallback
433
926
  actually on screen — slottables only, so a comment you wrote into fallback content is not in it,
@@ -439,139 +932,88 @@ render(() => html`<header>
439
932
  root the same line works, because there nothing moves. `before()`/`after()` route through the
440
933
  node's own current parent, so they are correct in both modes, and the content lands in the order
441
934
  you asked for. This is the sharpest difference between the two modes and the easiest to hit.
442
- - **A displaced node is *disconnected* here; native slotting never disconnects it.** Shadow
443
- distribution is virtual — a slottable no slot names stays in the light tree, connected, merely
444
- unrendered. Light slots park it physically, so a custom element inside displaced content runs its
445
- `disconnectedCallback` (and a Vera component's effect cleanups) on the way out, and
446
- `connectedCallback` again when its slot returns — with its element identity, stores and typed-in
447
- state intact, and reactivity re-established by the re-init. Component authors already handle this
448
- pair for any `appendChild` move; the difference is only *when* it happens: a component that
449
- pauses a video on disconnect pauses while displaced here and keeps playing in a shadow root.
450
- The slot element is deliberately not in your DOM (see below), so it is unreachable by selector and
451
- reports `isConnected === false`. It is a live API object, not a position in the tree.
935
+ - **A slotted component is MOVED into its slot, and a Vera component is not torn down by it.** Each
936
+ slotted node goes from where it is to where it is shown in ONE DOM operation, which core treats as a
937
+ move: a component that called `init()` keeps its effects, state and setup through it — nothing runs
938
+ twice, as nothing runs twice under native slotting, where nothing moves at all. A custom element
939
+ that is not a Vera component gets the platform's callbacks for a move: `disconnectedCallback` and
940
+ then `connectedCallback`.
941
+ - **A node no slot takes stays connected, and is not rendered — as under native slots.** A light
942
+ host has no second tree to hide it in, so it waits in a hidden container the host is given for
943
+ the purpose, `<ins hidden data-vm-unassigned>`, its FIRST child: a component in it keeps running (its
944
+ effects stay live), it is still in the host's tree for `querySelector`, as a native unassigned
945
+ light child is, and when a
946
+ slot for it appears it moves there in one operation and is kept. The container is there only
947
+ while it holds something, so a host whose content is all assigned has no extra child. When it is
948
+ there, it is a child of your host like any other: `host.children`, `:scope > *`, `:first-child`,
949
+ `:nth-child()` and `:empty` see it — write `:scope > :not([data-vm-unassigned])` where that matters.
950
+ It stays hidden whatever a stylesheet says (an inline `display: none !important` beside `hidden`).
951
+ It is a standard element, so it is valid HTML around any content, and `:defined`: a lazy loader
952
+ or a "wait until every element is defined" check never waits on it.
452
953
  - **`name` can be a binding.** `<slot name=${section}>` routes by the name it actually has, and
453
954
  re-routes if it changes between renders.
454
955
 
455
- ### Keeping the `<slot>` in the tree — a strategy you can own
456
-
457
- Every boundary above has one cause: the shipped strategy removes the `<slot>` element so your
458
- markup stays exactly what you wrote. The seam it registers through is public, single-registrant,
459
- and takes whole strategies — so if you would rather have the *shadow tree's own structure* (the
460
- slot element present, selectable, `:first-child`-countable, made layout-invisible by the same
461
- `display: contents` the UA stylesheet gives real slots), you can wire a strategy that keeps it.
462
- This one is complete enough to run — and it runs, in CI, as written:
463
-
464
- <!-- recipe -->
465
- ```js
466
- import { init, render, wire, html } from '@verajs/core';
467
- import { renderer } from '@verajs/renderer';
468
-
469
- /** Distribution that KEEPS the <slot>: content moves INSIDE it, fallback shows when it is empty. */
470
- const slotsInTree = {
471
- name: 'my-app/slots-in-tree',
472
- on: 'slot',
473
- priority: 50,
474
- fn(slot, root, name) {
475
- if (root.nodeType !== 1) return null; // a shadow root keeps native slotting
476
- const host = root;
477
- const fallback = [...slot.childNodes];
478
- const isMine = (n) =>
479
- n.nodeType === 1 ? (n.getAttribute('slot') ?? '') === name
480
- : name === '' && n.nodeType === 3 && n.data.trim() !== '';
481
- let shown = -1;
482
- const fill = () => {
483
- for (const n of [...host.childNodes]) if (isMine(n)) slot.append(n);
484
- const assigned = [...slot.childNodes].filter((n) => !fallback.includes(n));
485
- for (const n of fallback) (assigned.length ? n.remove() : slot.append(n));
486
- observer.takeRecords(); // our own moves are not the user's
487
- if (assigned.length !== shown) {
488
- shown = assigned.length;
489
- slot.dispatchEvent(new Event('slotchange', { bubbles: true })); // real ancestors — it CLIMBS
490
- }
491
- };
492
- const observer = new MutationObserver(fill);
493
- fill();
494
- observer.observe(host, { childList: true, subtree: true });
495
- return { _$park$: () => { observer.disconnect(); for (const n of [...slot.childNodes]) if (!fallback.includes(n)) host.append(n); } };
496
- },
497
- };
498
-
499
- wire([renderer, slotsInTree]);
500
- document.head.insertAdjacentHTML('beforeend', '<style>slot{display:contents}</style>');
501
-
502
- customElements.define('tree-card', class extends HTMLElement {
503
- connectedCallback() {
504
- init(this);
505
- render(() => html`<article><slot name="header">Untitled</slot></article>`);
506
- }
507
- });
508
-
509
- const card = document.createElement('tree-card');
510
- card.innerHTML = '<h2 slot="header">Hello</h2>';
511
- document.body.append(card);
512
- await new Promise((resolve) => requestAnimationFrame(resolve));
513
-
514
- /** Every documented boundary of the shipped strategy, working: */
515
- let heard = 0;
516
- card.addEventListener('slotchange', () => heard++); // a HOST-level listener — bubbling exists here
517
- if (!card.querySelector('slot')) throw new Error('querySelector finds the slot');
518
- if (card.querySelector('h2').parentElement.localName !== 'slot') throw new Error('reverse lookup');
519
- card.querySelector('h2').remove();
520
- await new Promise((resolve) => setTimeout(resolve, 0));
521
- if (card.querySelector('article').textContent !== 'Untitled') throw new Error('fallback returns');
522
- if (heard !== 1) throw new Error('slotchange bubbled to the host');
523
- ```
524
-
525
- The trade is the one the platform itself makes: this is the shadow tree's structure, so the
526
- `<slot>` now appears in your host's serialized markup (as it appears in a `shadowRoot`'s), your
527
- component CSS can select it — and structural selectors written against the template see it as the
528
- child it is, because selectors follow the tree, not layout. Wire it *instead of* `slots` — the
529
- seam is single-registrant, and wiring both says so in development, by name.
530
-
531
- What this recipe deliberately does not do is the audited module's territory: light-tree ordering
532
- under re-slots and prepends, duplicate-name handover, nested slots in fallbacks, dynamic
533
- `name=${…}`, SSR and hydration. It is a starting point you own, not a drop-in peer — the measured
534
- design for a full sibling lives with the maintainers.
535
-
536
- **The one thing a light-DOM slot cannot carry is presentation** — `class`, `style`, `id` and other
537
- plain attributes. A light host has no second tree, so the slot element is not rendered and there is
538
- nothing for them to apply to, while in a shadow root they do apply. Put them on a real element
539
- around the slot. Development builds say so, naming the attribute, rather than leaving it to be
540
- found.
956
+ **A `<slot>` carries presentation only while it shows its fallback** — `class`, `style`, `id` and
957
+ other plain attributes. Once it has content it steps out of the page and its attributes go with it,
958
+ while in a shadow root they keep applying. Put them on a real element around the slot. Development
959
+ builds say so, naming the attribute, rather than leaving it to be found.
541
960
 
542
961
  Additive like `keyed`/`spread`: it imports no renderer and reaches the one present through the wired
543
962
  seam, so it is safe beside any renderer entry on a CDN page. The entry is
544
- **<!--size:slots.gzip-->3.35 KB<!--/size:slots.gzip-->** gzipped and only apps importing it pay;
545
- `@verajs/renderer` itself carries just the seam that records where a template's slots are. It is
546
- also Node-safe — it imports nothing and touches no global document — so a universal app can wire it
547
- on both sides.
963
+ **<!--size:slots.gzip-->6.22 KB<!--/size:slots.gzip-->** gzipped and only apps importing it pay;
964
+ `@verajs/renderer` itself carries only generic hooks it plugs into. It is also Node-safe to import —
965
+ it imports nothing and touches no DOM until something renders — so a universal app can wire it on
966
+ both sides.
548
967
 
549
- ## `@verajs/renderer/hydrate`
968
+ ## `@verajs/renderer/hydration`
550
969
 
551
970
  <!-- recipe -->
552
971
  ```js
553
- import { renderer } from '@verajs/renderer/hydrate'; // instead of '@verajs/renderer'
554
- ```
972
+ import { wire } from '@verajs/core';
973
+ import { renderer } from '@verajs/renderer';
974
+ import { hydration } from '@verajs/renderer/hydration';
555
975
 
556
- Same name, same `wire([renderer])`, different entry — this one's `renderer` binds the adopting
557
- render below, so swapping the import (or the importmap target) really is the only change.
976
+ wire([renderer, hydration]);
977
+ ```
558
978
 
559
- The first render into a container that already has children **adopts** them as server output of the
560
- same template: node identity is preserved, listeners attach, and updates mutate the adopted nodes.
561
- Hydration here is **markerless** — server HTML carries no framework comments, and the client repairs
562
- its own anchors into the adopted DOM.
979
+ One more module wired beside the renderer — nothing else changes. The first render into a container that already has
980
+ children **adopts** them as server output of the same template: node identity is preserved, listeners attach, and
981
+ updates mutate the adopted nodes. Hydration here is **markerless** — server HTML carries no framework comments (light
982
+ slots aside: each filled slot's content sits between two, see [`/slots`](#verajsrendererslots--light-dom-slots)), and
983
+ the client repairs its own anchors into the adopted DOM.
984
+
985
+ **Server-rendered HTML must be hydrated.** A client that does not wire `hydration` renders beside the server's markup
986
+ — two copies, the server's dead — because a first render appends, and markup without a marker cannot be recognized.
987
+ The one case that can be: with slots wired, the server states every component host it renders, so on a client
988
+ without `hydration` a host stated empty (no light content) is cleared and rendered once, and a host holding the page's
989
+ light content stands exactly as served with a coded error (`hydration-unwired`; development names what to wire); development warns
990
+ once per page. A host that arrives with no children at all is simply rendered fresh, whatever its statement says, since
991
+ there is nothing to duplicate or lose. Its `data-vm-light` attribute is then left in place. That is harmless: only a
992
+ host's first render ever reads it, and a server re-states it on every render, so a copy of the live page (an editor's
993
+ save, a devtools copy of `outerHTML`) carrying it is no different from served markup.
563
994
 
564
995
  Any disagreement with the server markup clears the container (keeping `<style data-vm-sheet="styles">` tags)
565
996
  and renders fresh, so correctness never depends on the server output being right. A DOM node at a
566
997
  child position is the one thing the server cannot have rendered; it is inserted without giving up
567
998
  adoption of everything around it.
568
999
 
569
- **A fallback warns in development, naming the first place the two renders disagreed** — *"expected
570
- `<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does not describe"*. The page
1000
+ **A fallback warns in every build, naming the first place the two renders disagreed** — development
1001
+ spells it out, *"expected `<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does
1002
+ not describe"*; production prints the kind and the node it found. It is said once per kind of
1003
+ disagreement per hydration pass, so a list whose every row disagrees the same way is one line. The page
571
1004
  is correct either way, which is the point of the fallback and also why it needs saying: that
572
1005
  container's markup was just thrown away, and with nothing observable to notice, the only symptom is
573
- a first paint that is slower than the one you paid a server render for. An attribute that disagrees
574
- is simply re-set during adoption and is not a fallback at all.
1006
+ a first paint that is slower than the one you paid a server render for. An attribute is **read** during
1007
+ adoption and written only if it disagrees — a right one costs no write, a wrong one is repaired — and
1008
+ neither is a fallback.
1009
+
1010
+ **Form state stands.** A form control's `.value`, `.checked` and `.selected`, a `!name` on a built-in
1011
+ element and a `<select>`'s selection are recorded, not written, so whatever the user typed before the
1012
+ script arrived is kept (a `!name` then compares on the next render and takes over, as it always does).
1013
+ **Whoever writes an element's content owns its verification.** A custom element's children are its own
1014
+ render: when the template writes nothing inside the tag, adoption leaves them to the component (what the
1015
+ template does write inside it is compared as usual). And an element whose whole content is one `${…}`
1016
+ adopts as that value's range, with no marker put in.
575
1017
 
576
1018
  **A fallback costs one container, not the page.** Adoption is decided per container, so components
577
1019
  hydrating into their own roots are independent: one that disagrees rebuilds and warns, and every
@@ -584,23 +1026,22 @@ required in the server markup, and one in the server markup that your template d
584
1026
  a disagreement. A comment renders nothing, so neither direction changes what a reader sees; matching
585
1027
  on them would only cost every commented template its adoption.
586
1028
 
587
- On a CDN page, point the import map's `@verajs/renderer` at `vera-renderer-hydrate.min.js` and
588
- nothing else changes. Apps that never hydrate download none of this.
1029
+ On a CDN page, load `vera-renderer-hydration.min.js` beside `vera-renderer.min.js` and wire both. Apps that never
1030
+ hydrate download none of this.
589
1031
 
590
1032
  ### Importing this in Node
591
1033
 
592
1034
  **`@verajs/renderer` needs a DOM to be imported at all**, not merely to render. It captures
593
- `document` at module scope and builds two shared `TreeWalker`s there, which is what saves an
594
- allocation per instance — so `import '@verajs/renderer'` on a server throws
1035
+ `document` at module scope (and creates its scratch fragment there) — so `import '@verajs/renderer'` on a server throws
595
1036
  `ReferenceError: document is not defined` before any of your code runs. The same is true of
596
- `/hydrate` and `/profiler`, and of `@verajs/jsx/standalone`, which contains a renderer.
1037
+ `/profiler`, and of `@verajs/jsx/standalone`, which contains a renderer.
597
1038
 
598
1039
  This is worth stating because [`@verajs/router`](../router#node-and-ssr) documents the opposite
599
1040
  about itself, and the asymmetry is easy to read the wrong way. The rest of the family is Node-safe:
600
1041
  `@verajs/core`, `@verajs/inserts`, `@verajs/store` and `/collections`, `@verajs/router`,
601
1042
  `@verajs/styles`, `@verajs/autoloader`, `@verajs/jsx` (the transform), `@verajs/ssr` — **and
602
- `@verajs/renderer/keyed`, `/spread` and `/tag`**, which hold no DOM of their own even though their
603
- parent entry does.
1043
+ `@verajs/renderer/keyed`, `/spread`, `/tag`, `/hydration` and `/hydrate-slots`**, which hold no DOM of their own even
1044
+ though their parent entry does.
604
1045
 
605
1046
  In a universal app, hand the renderer in rather than importing it in shared code — which is what
606
1047
  `examples/kitchen-sink/wiring.js` does, taking it as a parameter so the server can pass `null`.
@@ -612,7 +1053,7 @@ Spread a props object onto an element, with names resolved at runtime.
612
1053
 
613
1054
  <!-- recipe -->
614
1055
  ```js
615
- import { init, createStore, render, wire, html } from '@verajs/core';
1056
+ import { init, createStore, wire, html } from '@verajs/core';
616
1057
  import { renderer } from '@verajs/renderer';
617
1058
  import { spread } from '@verajs/renderer/spread';
618
1059
 
@@ -622,16 +1063,17 @@ customElements.define(
622
1063
  'x-field',
623
1064
  class extends HTMLElement {
624
1065
  connectedCallback() {
625
- init(this, { mode: 'open' });
626
- const state = createStore({ disabled: false });
627
- const props = {
628
- id: 'email', // attribute
629
- placeholder: 'you@example.com', // "
630
- '.value': '', // property
631
- '?disabled': state.disabled, // boolean attribute
632
- onInput: (e) => console.log(e.target.value), // event — @input works too
633
- };
634
- render(() => html`<input ${spread(props)} />`);
1066
+ init({ host: this, shadow: 'open' }, () => {
1067
+ const state = createStore({ disabled: false });
1068
+ const props = {
1069
+ id: 'email', // attribute
1070
+ placeholder: 'you@example.com', // "
1071
+ '.value': '', // property
1072
+ '?disabled': state.disabled, // boolean attribute
1073
+ onInput: (e) => console.log(e.target.value), // event — @input works too
1074
+ };
1075
+ return () => html`<input ${spread(props)} />`;
1076
+ });
635
1077
  }
636
1078
  }
637
1079
  );
@@ -672,7 +1114,7 @@ html`<calendar-day ${props({ date, events })}></calendar-day>`
672
1114
  <calendar-day date={date} events={events} /> // JSX only: bare props ARE props on a component tag
673
1115
  ```
674
1116
 
675
- One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognises an
1117
+ One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognizes an
676
1118
  already-branded result, so the two spellings are literally the same call. In JSX the bag is
677
1119
  optional altogether: on a dash-named tag a bare prop compiles to the `.name` binding directly
678
1120
  (`@verajs/jsx`'s README has the two attribute carve-outs), so `props()` is the template's
@@ -698,7 +1140,7 @@ Three rules, each earned:
698
1140
 
699
1141
  Nothing to declare on the other side — no `static properties`, no props argument. A component that
700
1142
  calls `init()` finds every bound property on `this`, **reactively**: reading `this.date` in a
701
- render tracks it, the parent's next commit re-renders, and a store or `ref()` passed through stays
1143
+ render tracks it, the parent's next commit re-renders, and a store or `signal()` passed through stays
702
1144
  live because it arrives by identity. The full reception contract — including what happens when the
703
1145
  component's module loads *after* the parent rendered — is documented with `init()` in
704
1146
  `@verajs/core`'s README; this package's half is the delivery:
@@ -753,12 +1195,11 @@ written `@event` bindings behave too.
753
1195
 
754
1196
  ### What it costs, and why it is a separate entry
755
1197
 
756
- `@verajs/renderer` grows **5 B** gzipped for the protocol this uses, whether or not you import it —
757
- measured 2026-08-27 by deleting the `_$apply$` branch and rebuilding, as a **difference** rather than
758
- a pair of totals — the totals move with every change to this package and the difference does not,
759
- which is the mistake this line already made once. `llms.txt` and this file disagreed about the figure
760
- for a while, at 16 B and 8 B respectively, and both were wrong. Nothing regenerates it, so it is
761
- dated; re-measure the same way if it matters.
1198
+ `@verajs/renderer` grows **25 B** gzipped for the protocol this uses, whether or not you import it —
1199
+ measured 2026-09-28 by deleting the `_$apply$` branch and its teardown guard (a released ref must not
1200
+ write `.value = null` onto an object that applies itself) and rebuilding, as a **difference** rather
1201
+ than a pair of totals — the totals move with every change to this package and the difference does not.
1202
+ Nothing regenerates it, so it is dated; re-measure the same way if it matters.
762
1203
  The entry itself is **<!--size:spread.gzip-->1.60 KB<!--/size:spread.gzip-->** gzipped, and only apps
763
1204
  that import it pay for that.
764
1205
 
@@ -771,7 +1212,7 @@ small and fast, and it is why neither this renderer nor lit-html has spread buil
771
1212
 
772
1213
  The renderer itself holds only a protocol: a value at element position carrying `_$apply$` applies
773
1214
  itself. Everything else lives in this entry, which imports nothing — not even from the renderer — so
774
- it loads alongside any renderer that honours the protocol, including your own.
1215
+ it loads alongside any renderer that honors the protocol, including your own.
775
1216
 
776
1217
  ## `@verajs/renderer/profiler`
777
1218
 
@@ -831,17 +1272,66 @@ renderInto(html`<div .innerHTML=${trustedMarkup}></div>`, host);
831
1272
 
832
1273
  Greppable, obviously yours, reviewable as the security decision it is. Sanitize first
833
1274
  (`DOMPurify.sanitize`) unless the markup is genuinely your own, and put it on an element whose
834
- children nothing else binds — the renderer owns the content of elements it renders into.
1275
+ children nothing else binds — the renderer owns the content of elements it renders into. `@verajs/ssr`
1276
+ serializes it into the served page and hydration adopts it, behaving as the assignment does: a `<script>` in it
1277
+ never runs and a `<template shadowrootmode>` never attaches, on either side.
1278
+
1279
+ **Only a tagged template is a template.** A value renders as markup only when its strings came from a tagged
1280
+ template literal — an array owning `raw`, which nothing from `JSON.parse` can be. Data shaped like a template (an
1281
+ API field an attacker turned into `{"strings": [...]}`, a real template sent through JSON, or a hand-built
1282
+ `html([markup])`) renders as the text any object does, `[object Object]`, here and in `@verajs/ssr` alike — and here,
1283
+ in development, with a warning each time a new one arrives. Never a throw: the value is attacker-controlled, and a throw would hand over the subtree. The
1284
+ check runs where a template is first built, so a cached template pays nothing. (An ordinary object interpolated
1285
+ as a child renders as `String(object)`, as before; one that cannot convert — a parsed `"toString"` key — throws,
1286
+ as it does in React. Render a field, not a raw API object.)
1287
+
1288
+ **Development tells you; production pays nothing.** Misuse the renderer can see in a template's own source, or in an
1289
+ obviously wrong call, is caught in development: a template that cannot work as written throws there (a name
1290
+ expression, below; a value in TAG position, `<${x}>`, which needs a tag value from `@verajs/renderer/tag`;
1291
+ `renderInto` without a container; `keyed` without a template; a template ending inside a tag; a binding beside or
1292
+ inside an element in an SVG/MathML `<title>` or `<style>`, which this renderer reads as text, or inside the obsolete
1293
+ `<xmp>`, `<noembed>`, `<noframes>` and `<plaintext>`, which the parser does), and a mistake that still renders
1294
+ but not as meant is a `[vera]` warning (a self-closed `<div />`, a boolean child, a value that cannot
1295
+ listen, `@clik`, a binding on an element the parser drops, content in the wrong namespace, a repeated key) — said
1296
+ once where the mistake is in the template's source, and each time it happens where it is in a value (a boolean
1297
+ child, a value that cannot listen, a repeated key). None of
1298
+ it exists in the production build — those bundles are byte-for-byte what they would be without it.
1299
+
1300
+ **An attribute name cannot be an expression.** `<p data-${key}="1">` (or `<b ${name}="x">`, or
1301
+ `<p ${key}-x>`) throws in development when the template is first used — `@verajs/ssr` refuses it in every
1302
+ build — because the parser reads a name before any value exists. (Production pays nothing for the check:
1303
+ a template is fixed source, so its first development render finds it.) A name known only at runtime is a spread —
1304
+ `${spread({ [`data-${key}`]: '1' })}` — which refuses what a runtime name must not become (an inline handler,
1305
+ `srcdoc`, a `javascript:` URL); in development the error shows that rewrite for your template.
1306
+
1307
+ **Security: a bound URL cannot be a `javascript:` URL, and a bound `srcdoc` is refused.** A value
1308
+ bound where a browser *navigates* — `href`, `src`, `action`, `formaction`, `xlink:href` or `data`,
1309
+ as the attribute or as its property — is refused when it parses as a `javascript:` URL, and the
1310
+ attribute is removed. The same holds for an SVG animation's `to`, `from`, `by` and `values` (every item
1311
+ of a `values` list), on any element and whatever `attributeName` says: `<animate>`/`<set>` write their
1312
+ value onto the attribute they animate, `href` included, and Chromium, Firefox and WebKit all run a
1313
+ `javascript:` URL set on a link that way when it is clicked. It is read the way the URL Standard reads
1314
+ a scheme, so `" jAvA\tscript:"` is caught as surely as `javascript:`, and it is judged on the whole JOINED value, so `href="java${x}"` is
1315
+ caught too; the statics you write are yours and are never refused on their own. A value that is not a
1316
+ string is converted ONCE and the string checked is the string written, so an object whose `toString`
1317
+ changes its answer cannot pass as one URL and land as another. A custom element's property of the same
1318
+ name (`<my-chart .data=${rows}>`) is its own business: an object arrives untouched, and only a string is
1319
+ checked. A bound `srcdoc`
1320
+ *attribute* is refused outright, because it renders its value as an HTML document —
1321
+ `.srcdoc=${trusted}` is the deliberate spelling, exactly as `.innerHTML` is. There is no opt-out for
1322
+ URLs. `@verajs/ssr` applies the same rule, so a server never serves a link the client refuses.
1323
+ Development builds name each refusal.
835
1324
 
836
1325
  **Security: spread refuses the injection sinks.** The `.innerHTML` posture above rests on the
837
1326
  template spelling being greppable, obviously yours, and reviewable — three properties a spread key
838
1327
  does not have, because spread names arrive at runtime inside a props object that is often built
839
1328
  from data. So `spread()` refuses `.innerHTML`/`!outerHTML` property keys, the `srcdoc` attribute,
840
- and any inline-handler attribute name (`onclick` and friends, any casing — `on` + Capital with a
841
- function remains the documented event spelling and still works), on the client AND in the SSR
842
- serializer alike. Development builds name each refused key and the sanctioned template spelling.
1329
+ any inline-handler attribute name (`onclick` and friends, any casing — `on` + Capital with a
1330
+ function remains the documented event spelling and still works), and — as a template binding is —
1331
+ a `javascript:` URL on a key a browser navigates (`href`, `.href` and the rest), on the client AND
1332
+ in the SSR serializer alike. A key's verdict is decided once, when it first appears, not per render. Development builds name each refused key and the sanctioned template spelling.
843
1333
  If you genuinely need one of these dynamically, write the binding in the template where a reviewer
844
- can see it.
1334
+ can see it — for `srcdoc`, the property: `.srcdoc=${trusted}`.
845
1335
 
846
1336
  ## `@verajs/renderer/tag`
847
1337
 
@@ -885,7 +1375,7 @@ component: `@verajs/jsx` consumes it into `keyed(…)` for both spellings, and a
885
1375
  `H({ key })` drops it and says so in development, because a key marks a template for reconciliation
886
1376
  and this call *returns* one rather than being one.
887
1377
 
888
- **`dangerouslySetInnerHTML` is the one React name a tag cannot honour, and that is a security
1378
+ **`dangerouslySetInnerHTML` is the one React name a tag cannot honor, and that is a security
889
1379
  property rather than a gap.** A tag reaches its element through `/spread`, whose names are only
890
1380
  known at runtime — which is exactly what makes that sink unreviewable — so `/spread` refuses
891
1381
  `.innerHTML` outright. Write the element directly, with the value sanitized first:
@@ -911,7 +1401,7 @@ life of three defects.
911
1401
  writing tests for it.
912
1402
  - HTML only. There is no `svg`/`mathml` equivalent yet.
913
1403
 
914
- <!--size:tag.gzip-->2.20 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
1404
+ <!--size:tag.gzip-->2.36 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
915
1405
  needs it to apply props whose names it cannot know. Additive, like `/spread` and unlike the other
916
1406
  entries: it inlines no renderer internals, so it is safe alongside any of them.
917
1407
 
@@ -933,18 +1423,29 @@ BOOLEAN_ATTRIBUTES.has('disabled'); // true — the names the tag entry toggles
933
1423
 
934
1424
  The renderer holds no directive system. It holds a **protocol**, at the two positions worth
935
1425
  extending, and everything built on it is an ordinary package the renderer knows nothing about —
936
- `@verajs/renderer/spread` is the proof, at 5 B of protocol in this bundle and its own weight only
1426
+ `@verajs/renderer/spread` is the proof, at 25 B of protocol in this bundle and its own weight only
937
1427
  for apps that import it.
938
1428
 
939
1429
  | position | brand | called as |
940
1430
  | --- | --- | --- |
941
- | element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part)` |
942
- | child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous)` |
1431
+ | element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part, untracked, adopting)` |
1432
+ | child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous, adopting)` |
1433
+
1434
+ `adopting` is `true` exactly once, while `hydration` adopts server markup: leave form state
1435
+ alone, and adopt what the server rendered at the position or replace it — an applier that ignores the flag
1436
+ renders, which replaces. (`untracked` is how an applier runs someone else's code without subscribing the
1437
+ render — see core's `untrack`.)
943
1438
 
944
1439
  A child-position value carrying `_$child$` applies itself. It is handed the part and whatever it
945
1440
  returned last time **at that part**, and calls `part._$commit$(value)` to render content. That is
946
1441
  the whole surface: `until()` is nine lines against it.
947
1442
 
1443
+ Both kinds apply **mid-commit** — `_$apply$` has to, because properties must reach an element before it
1444
+ is inserted and upgraded. So an element an applier receives may not be in its document yet: a template
1445
+ with no custom element is cloned from the browser's inert template document and inserted after its
1446
+ values commit. Read the realm lazily (`element.ownerDocument.defaultView` when it is needed, not at apply
1447
+ time), or use a ref, which runs once the element is in place.
1448
+
948
1449
  ```js
949
1450
  /** Hoisted — the applier's identity is its own continuity key. */
950
1451
  function applyUntil(part, previous) {
@@ -963,7 +1464,7 @@ renderInto(html`<p>${until(fetchUser(), html`<em>loading…</em>`)}</p>`, host);
963
1464
  Three rules, each of which is a real trap:
964
1465
 
965
1466
  - **Hoist the applier.** Written as an object-literal method it is a new function per call, so the
966
- part can never recognise it and `previous` is always `undefined`. Its identity is what keeps two
1467
+ part can never recognize it and `previous` is always `undefined`. Its identity is what keeps two
967
1468
  appliers at one part from reading each other's state.
968
1469
  - **Continuity lives in the return value**, not in an applier instance. That is what makes this a
969
1470
  protocol rather than a framework — no base class, no `directive()` factory, no lifecycle.
@@ -1009,9 +1510,11 @@ The check costs the hot path nothing: it sits after the template branch, and a t
1009
1510
  common object at a child position — returns before ever reading it, so only arrays, nodes and
1010
1511
  appliers pay a property read. Measured with no runtime difference distinguishable from noise.
1011
1512
 
1012
- The whole protocol is **116 B gzipped** — the check, the two fields holding an applier's state and
1013
- whose it is, the save/restore in `_$commit$` that stops an applier's own rendering from destroying
1014
- its continuity, and the `_$detach$` call. It was 94 B before teardown existed.
1513
+ The whole protocol is **134 B gzipped** (measured 2026-09-28 by deleting it and rebuilding) — the
1514
+ check, the two fields holding an applier's state and whose it is, the save/restore in `_$commit$` that
1515
+ stops an applier's own rendering from destroying its continuity, running a commit that arrives after
1516
+ the render returned as a render of the container that attached it (so it builds in that container's document and
1517
+ its refs run once it is done), and the `_$detach$` call.
1015
1518
 
1016
1519
  ## Animating things in and out
1017
1520
 
@@ -1064,7 +1567,7 @@ Directives other renderers ship, and what replaces them here.
1064
1567
  | --- | --- |
1065
1568
  | `repeat()` | `keyed()` |
1066
1569
  | `cache()` | `hold()` |
1067
- | `ref()` | an element-position expression, `<input ${myRef}>` |
1570
+ | `signal()` | an element-position expression, `<input ${myRef}>` |
1068
1571
  | `ifDefined()` | built in — `null`/`undefined` remove an attribute |
1069
1572
  | `classMap()` / `styleMap()` | build the string: `class="base ${extra}"` |
1070
1573
  | `guard()` | reactivity already skips unchanged work |